[ mikey's blog ]

BadNews Template Documentation

Overview:

The BadNews content management system uses the Template Toolkit by Andy Wardley for it's templating system. The templates are passed a collection of BadNews objects combined into one easily accessable "toolshed" which you can use to access the many aspects of the BadNews cms.

The purpose of this document is to document the specifics of the BadNews interfaces available via the Template Toolkit. If you need help with the Template Toolkit templating language, please visit http://www.template-toolkit.org/docs.html to read the documentation. We will provide examples using tt2 in this document, so if you are unfamiliar with the basics of the templating language, we reccomend that you go read the docs.

Conventions:

This document uses easy to read conventions to highlight code examples and important notes. Boxes like the one below will indicate that the text within is a Template Toolkit code example.

    [% IF fe.cgi.param('filter_type') %]
        [% filter_type = fe.cgi.param('filter_type') %]
    [% ELSE %]
        [% filter_type = 'All' %]
    [% END %]

Boxes like the one below will indicate important side notes, tips, and advanced explanations of techniques that we believe will be most beneficial to you.



The BadNews API / The Front End object (fe)

The FrontEnd object itself is designed to provide easy access to the many tools available to you as a template designer. This is an ever changing module, and as more and more people use this and request access to certain parts of the BadNews system it will grow and change and become even more intuitive and easy to use.

Two methods (functions / whatever you wanna call them) that provide the most flexability are the fe.param and the fe.cgi methods. The fe.cgi object is just a standard CGI.pm object brought into the template. The only real value I can think of right now for this is to be able to pull parameters and values out of it, so to make it easy I wrote the fe.param wrapper around fe.cgi.param(). An example follows.

    [% article_id = fe.param('article_id') %]

To manage links, the FrontEnd object offers two methods; fe.all_links(), and fe.links_by_cat(). fe.all_links() simply returns a list of all the links in the system in the form of BadNews::Links objects. fe.links_by_cat() allows you to specify a category of links to filter on. An example follows.

    [% FOREACH link = fe.links_by_cat("File Sites") %]
        
            [% link.short_name %]i
        
    [% END %]

Calendaring support in BadNews is fairly thin as of the 0.05 release. What we do have are basic events, with descriptions, dates, times, places, and a published flag. At the moment there are no recurring events, though if there ever are I promise not to change the API too much. There are currently four methods available for calendar functionality. fe.open_event() which takes one arguement, the event id of the event you wish to open. It returns a BadNews::Calendar::Event object.

    [% event = fe.open_event(3) %]

The two other methods that have to do with calendaring are wrappers around the BadNews::Calendar::Day class and the BadNews::Calendar class, they are fe.day() which takes a three arguements month(MM), day(DD), and year(YYYY) in that order. The other method is fe.cal() which takes two arguements month(MM) and year(YYYY) in that order. They each return their respective objects.

    [% calendar = fe.day('09', '27', '1980') %]

There are a couple methods for dealing with files, the fe.all_files() method returns all the files in the BadNews system. This usually won't be what you want, luckily we provide a mechanism for fine grained file searches. The fe.file_search() method is a good way to search for files by the following criteria:

• all files
  • file_name
  • media_type
  • file_type
  • description
• image files
  • height
  • width
• music files
  • artist
  • time
  • album
  • track
  • song_name
  • year
• document files
  • content

Here is an example using fe.file_search():

    [% FOREACH file = fe.file_search(file_name => 'txt') %]
        
            [% file.name %]
        
    [% END %]

One convienience method left, the fe.author_by_name() method takes an author name, (username, login, whatever you want to call it) and returns an author object. This gives you really only one thing, access to the common_name method which belongs to the BadNews::Author class. Why not give you an example while I'm at it...

    [% author = fe.author_by_name(article.author) %]
    
awesome article by [% author.common_name %]

The BadNews API / The ArticleInterface object (fe.ai)

The ArticleInterface object is an extensive interface to your BadNews articles. There are a dozen or so methods in this object that will be useful to you through the templating interface. Looking at the api, it doesn't look like some of these methods should be here, and they might move. Here is a method summary:

• article related methods
  • fe.ai.all_articles()
  • fe.ai.recent_articles()
    • first arguement: the number of recent articles to return
    • second arguement: the number of articles to omit from the search (newest first)
  • fe.ai.count_recent_articles()
    • takes same arguements as fe.ai.recent_articles() just returns a count
  • fe.ai.articles_by_category()
    • first arguement: the category to seek out articles from
    • second arguement: the number of articles to return
  • fe.ai.count_articles_by_category()
    • takes same arguements as fe.ai.count_articles_by_category() just returns a count
  • fe.ai.open_article()
    • first arguement: the article id
  • fe.ai.articles_by_date_range()
    • first arguement: the starting date and time in diminished time YYYYMMDDHHMMSS
    • second arguement: the ending date and time in diminished time YYYYMMDDHHMMSS
    • third arguement: either the word 'create' or 'modify' depending on which timestamp you want to check
  • fe.ai.count_articles_by_date_range()
    • takes same arguements as fe.ai.articles_by_date_range() just returns a count
• misc methods
  • fe.ai.pretty_date()
    • first arguement: a date in diminished time
  • fe.ai.all_links()
  • fe.ai.all_files()
  • fe.ai.all_images()
  • fe.ai.author_cn()
    • first arguement: the authorname of the author you want the cn of
  • fe.ai.list_categories
  • fe.ai.list_non_system_categories

Since I believe these will be the methods most of you use for almost everything I'll go into a little bit of detail and provide some examples of working with each.